EzyPayment - as a Service (EPaaS)
API Spec Summary
API version : v1
EzyPayment host : https://stagingapp.sgebiz.com
EzyPayment BASE URL : {ezypayment_host}/x-ex-payment/api
| API ID | API Name | API Resource | Security | Calling Party | Receiving Party |
|---|---|---|---|---|---|
| API_R01 | Initiate Payment Redirection | {ezypayment_base_url}/init/payment/redirection | PGP Signature parameter | External Party | EzyPayment |
| API_R02 | Payment Response Redirection | {redirect url from external party} | PGP Signature parameter | EzyPayment | External Party |
| API_B01 | Payment Response Callback | {external party base url from registration}/status/payment | PGP signed and encrypted payload | EzyPayment | Ezternal Party |
| API_B02 | Get Payment Status | {ezypayment_base_url}/status/payment | PGP signed and encrypted payload | External Party | EzyPayment |
| API_B03 | Remittance Response Callback | {external party base url from registration}/status/remittance | PGP signed and encrypted payload | EzyPayment | Ezternal Party |
| API_B04 | Get Remittance Status | {ezypayment_base_url}/status/remittance | PGP signed and encrypted payload | External Party | EzyPayment |
API_R01 : Initiate Payment Redirection
External party can initiate this redirection once customer click on pay. The API should call as a browser location or a web location instead of a GET rest API call, since this will open the EzyPayment payment page.
| URL | https://{ezypayment_host}/x-ex-payment/api/{version}/init/payment/redirection |
| Description | Redirects the user from the External Party application to EzyPayment payment page. |
| HTTP Method | GET |
| Content type | N/A |
| Authentication | client id enforcement |
| Security | Secured with PGP signature in the query parameters. |
| Calling party | External Party |
Request : Headers
N/A
Request : Query Parameters
| Attribute | Description | Data type | Mandatory | Example |
|---|---|---|---|---|
| client_id | Issued client id of the external party. | String (max = 36 chars) | Y | abcd1234EfgH4398 |
| client_secret | Issued client secret of the external party. | String (max = 36 chars) | Y | xyz999-Abcirkls9827-kjsf8 |
| customer-name | Name of the customer, for reporting purpose. | String (max = 250 chars) | Y | Jack Sparrow |
| customer-mobile | Phone number of the customer, for reporting purpose. | String (max = 20 chars) | N | +6587654321 |
| customer-email | Email of the customer, for reporting purpose. | String (max = 250 chars) | Y | abcuser@mail.com |
| customer-ref | Unique reference to identify the customer. | String (max = 36 chars) | Y | U1237658 |
| invoice-amount | Invoice amount in SGD for the payment. | Double (10, 2) | Y | 12345678.12 |
| invoice-ref | Unique reference number for the payment. This should be unique throughout all the payments done by the external party. | String (max = 250 chars) | Y | INV1234 |
| invoice-description | Description of the invoice. This will be shown to customer on the payment page. | String (max = 250 chars) | N | Rental for month of May to be paid by Jack. No parley allowed. |
| purpose | Purpose of the payment. Must be one of accepted purposes. See Appendix for the list of purposes. | String (max = 50 chars) | N If not provided default will be taken from the Master purpose of external party. | Rent |
| redirect-back-url | Web URL of the page which should user redirect once the payment completed. Note that both success and failed completions will be redirect to this, with status attached. The URL should not have any query parameters. | String (max = 250 chars) | Y | https://mypage.com/payment-result |
| timestamp | Request timestamp in EPOC milliseconds | String (max = 15 chars) | Y | 1604536682681 |
| signature | Query parameters (as a Json string) should be signed with external party PGP private key and attach as the last query param. This will be used for verifying the request and prevent data manipulation. See Appendix on how to generate signature. | String | Y | ----BEGIN+PGP+SIGNATURE %0AVersion%3A+Didisoft+OpenPGP+Library+for+Java3.2%0A%0AiAAAAwUAYI vJx2sHx69l4WlKAQ {...} Ldqgf%2Yt2EkqXoqGqRPogFWFdZ6X2ise5jO%2BAm END+PGP+SIGNATURE ----%0Ai |
Request : Body
N/A
Responses
- 302
| Headers | location : {EzyPayment payment page URL} |
| Query params | N/A |
| Body | N/A |
API_R02 : Payment Response Redirection
Once user completed the payment flow (either success or failed), the user will be redirect back to the URL given in API_R01 with additional query params for status. It is up to the external party to set up this URL as a front-end URL or a backend GET URL.
| URL | https://{external_party_redirect_url_from_API_R01} |
| Description | Redirects the user from the EzyPayment to External Party application. |
| HTTP Method | GET |
| Content type | N/A |
| Authentication | N/A |
| Security | Secured with PGP signature in the query parameters. |
| Calling party | EzyPayment |
Request : Headers
N/A
Request : Query Parameters
| Attribute | Description | Data type | Mandatory | Example |
|---|---|---|---|---|
| status | Status of the payment transaction | String enum [SUCCESS, FAILED] | Y | SUCCESS |
| error-code | Error code of the error in case of an error occurred at the payment. See Appendix for the list of error codes. | String (max = 6 chars) | N | EP4000 |
| error-message | Error message of the error in case of an error occurred at the payment. See Appendix for the list of error messages. | String (max = 250 chars) | N | Insufficient funds |
| timestamp | Request timestamp in EPOC milliseconds | String (max = 15 chars) | Y | 1604536682681 |
| signature | Query parameters (as a Json string) should be signed with EzyPayment PGP private key and attach as the last query param. This will be used for verifying the request and prevent data manipulation. See Appendix on how to verify signature. | String | Y | ----BEGIN+PGP+SIGNATURE %0AVersion%3A+Didisoft+OpenPGP+Library+for+Java3.2%0A%0AiAAAAwUAYI vJx2sHx69l4WlKAQ {...} Ldqgf%2Yt2EkqXoqGqRPogFWFdZ6X2ise5jO%2BAm END+PGP+SIGNATURE ----%0Ai |
Request : Body
N/A
Responses
- It is up to the external party to handle the API.
API_B01 : Payment Response Callback
Once user completed the payment flow (either success or failed), the payment status will be pushed to External Party backend API. It is up to the external party to set up this URL as a backend POST API and handle the processing/storing the data.
| URL | https://{external_party_BASE_URL_from_registration}/status/payment |
| Description | Sends payment status from EzyPayment to External Party backend. |
| HTTP Method | POST |
| Content type | application/json |
| Security | Secured with PGP sign and encryption in request body. |
| Calling party | EzyPayment |
Request : Query Parameters
N/A
Request : Body
Request body is a PGP signed/encrypted payload as a string as follows.
"-----BEGIN PGP MESSAGE----- Version: Didisoft OpenPGP Library for Java 3.2 hQEMA63UlgaQT+XfAQgAjYasSxqx9dPiXK48dmylIWWvbKmt0PZ+ESz57akDEHHy ... BzubwsgqffLbaQ/bIuP7Hy+fhZs0LGN6aNz8vjyHRfqMxhtfQP2qxwZLWlHrqwwE WnKJye+bNAoemQUvaqxgrlmCM5l6InuLVQhQfk3Ppu2I =rDE6 -----END PGP MESSAGE-----"The encrypted data contains below fields.
| Attribute | Description | Data type | Mandatory | Example |
|---|---|---|---|---|
| customerRef | Same as API_R01. | String (max = 36 chars) | Y | U1237658 |
| invoiceAmount | Same as API_R01. | Double (10, 2) | Y | 12345678.12 |
| invoiceRef | Same as API_R01. | String (max = 250 chars) | Y | INV1234 |
| status | Status of the payment transaction | String enum [SUCCESS, FAILED] | Y | SUCCESS |
| transactionId | Auto generated unique payment transaction id | String (max = 50 chars) | Y | 2398790834kjfi39 |
| errorCode | Error code of the error in case of an error occurred at the payment. See Appendix for the list of error codes. | String (max = 6 chars) | N | EP4000 |
| errorMessage | Error message of the error in case of an error occurred at the payment. See Appendix for the list of error messages. | String (max = 250 chars) | N | Insufficient funds |
| timestamp | Request timestamp in EPOC milliseconds | String (max = 15 chars) | Y | 1604536682681 |
Responses
- 200
It is up to the external party to handle the API.
EzyPayment will expect the following response from external party to confirm that the data are accepted. Note that the response always should be in http status 200.
| Headers | N/A |
| Query params | N/A |
| Content-type | application/json |
| Encryption | Not needed |
Response Body
| Attribute | Description | Data type | Mandatory | Example |
|---|---|---|---|---|
| status | Whether accepted or not | String enum [OK, REJECTED] | Y | OK |
| reason | If the status is rejected then the reject reason | String (max = 255 chars) | N | Cannot verify the payload |
Response Body Example
{
"status": "OK"
}API_B02 : Get Payment Status
External party can call this API anytime to get details of payment transactions.
| URL | https://{ezypayment_base_url}/status/payment |
| Description | External party request payment status from EzyPayment. |
| HTTP Method | GET |
| Content type | application/json |
| Authentication | client id enforcement |
| Security | Secured with PGP sign and encryption in response body. |
| Calling party | External Party |
Request : Headers
| header | value | required |
|---|---|---|
| client_id | client id given in the registration | Y |
| client_secret | client secret given in the registration | Y |
| timestamp | Request timestamp in EPOC milliseconds | Y |
Request : Query Parameters
| Attribute | Description | Data type | Mandatory | Example |
|---|---|---|---|---|
| invoice-ref | A list of invoice ref numbers | Array of String (max = 250 chars) | N | INV1234,INV3453 |
| from-date | If need to filter by the dates | Datetime in format (yyyy-MM-dd'T'hh:mm:ss'Z') | N | 2023-01-01T00:00:00Z |
| to-date | If need to filter by the dates | Datetime in format (yyyy-MM-dd'T'hh:mm:ss'Z') | N | 2023-01-01T00:00:00Z |
Request : Body
N/A
Responses
- 200
Response body is a PGP signed/encrypted payload as a string as follows.
"-----BEGIN PGP MESSAGE----- Version: Didisoft OpenPGP Library for Java 3.2 hQEMA63UlgaQT+XfAQgAjYasSxqx9dPiXK48dmylIWWvbKmt0PZ+ESz57akDEHHy ... BzubwsgqffLbaQ/bIuP7Hy+fhZs0LGN6aNz8vjyHRfqMxhtfQP2qxwZLWlHrqwwE WnKJye+bNAoemQUvaqxgrlmCM5l6InuLVQhQfk3Ppu2I =rDE6 -----END PGP MESSAGE-----"The encrypted data contains below fields as Array of objects per invoice-ref in the request.
| Attribute | Description | Data type | Mandatory | Example |
|---|---|---|---|---|
| customerRef | Same as API_R01. | String (max = 36 chars) | Y | U1237658 |
| invoiceAmount | Same as API_R01. | Double (10, 2) | Y | 12345678.12 |
| invoiceRef | Same as API_R01. | String (max = 250 chars) | Y | INV1234 |
| status | Status of the payment transaction | String enum [SUCCESS, FAILED] | Y | SUCCESS |
| transactionId | Auto generated unique payment transaction id | String (max = 50 chars) | Y | 2398790834kjfi39 |
| errorCode | Error code of the error in case of an error occurred at the payment. See Appendix for the list of error codes. | String (max = 6 chars) | N | EP4000 |
| errorMessage | Error message of the error in case of an error occurred at the payment. See Appendix for the list of error messages. | String (max = 250 chars) | N | Insufficient funds |
| timestamp | Request timestamp in EPOC milliseconds | String (max = 15 chars) | Y | 1604536682681 |
API_B03 : Remittance Response Callback
Once the remittance has been done (either success or failed), the remittance status will be pushed to External Party backend API. It is up to the external party to set up this URL as a backend POST API and handle the processing/storing the data.
Note that the remittances may contain multiple payment transactions in some conditions. With the remittance status API will return the list of payments that it belongs to.
| URL | https://{external_party_BASE_URL_from_registration}/status/remittance |
| Description | Sends remittance status from EzyPayment to External Party backend. |
| HTTP Method | POST |
| Content type | application/json |
| Security | Secured with PGP sign and encryption in request body. |
| Calling party | EzyPayment |
Request : Query Parameters
N/A
Request : Body
Request body is a PGP signed/encrypted payload as a string as follows.
"-----BEGIN PGP MESSAGE----- Version: Didisoft OpenPGP Library for Java 3.2 hQEMA63UlgaQT+XfAQgAjYasSxqx9dPiXK48dmylIWWvbKmt0PZ+ESz57akDEHHy ... BzubwsgqffLbaQ/bIuP7Hy+fhZs0LGN6aNz8vjyHRfqMxhtfQP2qxwZLWlHrqwwE WnKJye+bNAoemQUvaqxgrlmCM5l6InuLVQhQfk3Ppu2I =rDE6 -----END PGP MESSAGE-----"The encrypted data contains below fields.
| Attribute | Description | Data type | Mandatory | Example |
|---|---|---|---|---|
| remittanceId | Auto generated remittance transaction id | String (max = 20 chars) | Y | abcd000092384 |
| remittanceRef | Auto generated remittance reference | String (max = 15 chars) | Y | bulk-payment |
| remittanceAmount | Combined remittance amount | Double (10, 2) | Y | 12345678.12 |
| status | Status of the remittance transaction | String enum [SUCCESS, FAILED] | Y | SUCCESS |
| errorCode | Code of the error, in case of an error occurred at the remittance. See Appendix for the list of error codes. | String (max = 6 chars) | N | EP4000 |
| errorMessage | Message of the error, in case of an error occurred at the remittance. See Appendix for the list of error messages. | String (max = 250 chars) | N | Invalid account number |
| timestamp | Request timestamp in EPOC milliseconds | String (max = 15 chars) | Y | 1604536682681 |
| payments | List of payments that relate to this remittance | Arry of Objects | Y | ... |
| payments.invoiceRef | Payment invoice reference | String (max = 250 chars) | Y | INV1234 |
| payments.transactionId | Payment transaction id | String (max = 50 chars) | Y | 2398790834kjfi39 |
Responses
- 200
It is up to the external party to handle the API.
EzyPayment will expect the following response from external party to confirm that the data are accepted. Note that the response always should be in http status 200.
| Headers | N/A |
| Query params | N/A |
| Content-type | application/json |
| Encryption | Not needed |
Response Body
| Attribute | Description | Data type | Mandatory | Example |
|---|---|---|---|---|
| status | Whether accepted or not | String enum [OK, REJECTED] | Y | OK |
| reason | If the status is rejected then the reject reason | String (max = 255 chars) | N | Cannot verify the payload |
Response Body Example
{
"status": "OK"
}API_B04 : Get Remittance Status
External party can call this API anytime to get details of remittance transactions.
| URL | https://{ezypayment_base_url}/status/remittance |
| Description | External party request remittance status from EzyPayment. |
| HTTP Method | GET |
| Content type | application/json |
| Authentication | client id enforcement |
| Security | Secured with PGP sign and encryption in response body. |
| Calling party | External Party |
Request : Headers
| header | value | required |
|---|---|---|
| client_id | client id given in the registration | Y |
| client_secret | client secret given in the registration | Y |
| timestamp | Request timestamp in EPOC milliseconds | Y |
Request : Query Parameters
| Attribute | Description | Data type | Mandatory | Example |
|---|---|---|---|---|
| invoice-ref | A list of invoice ref numbers | Array of String (max = 250 chars) | N | INV1234,INV3453 |
| from-date | If need to filter by the dates | Datetime in format (yyyy-MM-dd'T'hh:mm:ss'Z') | N | 2023-01-01T00:00:00Z |
| to-date | If need to filter by the dates | Datetime in format (yyyy-MM-dd'T'hh:mm:ss'Z') | N | 2023-01-01T00:00:00Z |
Request : Body
N/A
Responses
- 200
Response body is a PGP signed/encrypted payload as a string as follows.
"-----BEGIN PGP MESSAGE----- Version: Didisoft OpenPGP Library for Java 3.2 hQEMA63UlgaQT+XfAQgAjYasSxqx9dPiXK48dmylIWWvbKmt0PZ+ESz57akDEHHy ... BzubwsgqffLbaQ/bIuP7Hy+fhZs0LGN6aNz8vjyHRfqMxhtfQP2qxwZLWlHrqwwE WnKJye+bNAoemQUvaqxgrlmCM5l6InuLVQhQfk3Ppu2I =rDE6 -----END PGP MESSAGE-----"The encrypted data contains below fields as Array of objects per remittance matching to invoice-ref in the request.
| Attribute | Description | Data type | Mandatory | Example |
|---|---|---|---|---|
| remittanceId | Auto generated remittance transaction id | String (max = 20 chars) | Y | abcd000092384 |
| remittanceRef | Auto generated remittance reference | String (max = 15 chars) | Y | bulk-payment |
| remittanceAmount | Combined remittance amount | Double (10, 2) | Y | 12345678.12 |
| status | Status of the remittance transaction | String enum [SUCCESS, FAILED] | Y | SUCCESS |
| errorCode | Code of the error, in case of an error occurred at the remittance. See Appendix for the list of error codes. | String (max = 6 chars) | N | EP4000 |
| errorMessage | Message of the error, in case of an error occurred at the remittance. See Appendix for the list of error messages. | String (max = 250 chars) | N | Invalid account number |
| timestamp | Request timestamp in EPOC milliseconds | String (max = 15 chars) | Y | 1604536682681 |
| payments | List of payments that relate to this remittance | Arry of Objects | Y | ... |
| payments.invoiceRef | Payment invoice reference | String (max = 250 chars) | Y | INV1234 |
| payments.transactionId | Payment transaction id | String (max = 50 chars) | Y | 2398790834kjfi39 |